home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / Interfaces&Libraries / Universal / Interfaces / CIncludes / SoundSprocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  15.1 KB  |  461 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        SoundSprocket.h
  3.  
  4.      Contains:    Games Sprockets: SoundSprocket interfaces
  5.  
  6.      Version:    Technology:    NetSprocket 1.0
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1996-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __SOUNDSPROCKET__
  18. #define __SOUNDSPROCKET__
  19.  
  20. #ifndef __MACTYPES__
  21. #include <MacTypes.h>
  22. #endif
  23. #ifndef __EVENTS__
  24. #include <Events.h>
  25. #endif
  26. #ifndef __QD3D__
  27. #include <QD3D.h>
  28. #endif
  29. #ifndef __QD3DCAMERA__
  30. #include <QD3DCamera.h>
  31. #endif
  32.  
  33.  
  34.  
  35. #if PRAGMA_ONCE
  36. #pragma once
  37. #endif
  38.  
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42.  
  43. #if PRAGMA_IMPORT
  44. #pragma import on
  45. #endif
  46.  
  47. #if PRAGMA_STRUCT_ALIGN
  48.     #pragma options align=power
  49. #elif PRAGMA_STRUCT_PACKPUSH
  50.     #pragma pack(push, 2)
  51. #elif PRAGMA_STRUCT_PACK
  52.     #pragma pack(2)
  53. #endif
  54.  
  55. /*******************************************************************************
  56.  *    This stuff will be moved to Errors.h in a subsequent release
  57.  ******************************************************************************/
  58.  
  59. enum {
  60.     kSSpInternalErr                = -30340,
  61.     kSSpVersionErr                = -30341,
  62.     kSSpCantInstallErr            = -30342,
  63.     kSSpParallelUpVectorErr        = -30343,
  64.     kSSpScaleToZeroErr            = -30344
  65. };
  66.  
  67.  
  68. /*******************************************************************************
  69.  *    SndSetInfo/SndGetInfo Messages
  70.  ******************************************************************************/
  71. /*    The siSSpCPULoadLimit = '3dll' selector for SndGetInfo fills in a value of    */
  72. /*    type UInt32.                                                                */
  73.  
  74.  
  75. enum {
  76.     kSSpSpeakerKind_Stereo        = 0,
  77.     kSSpSpeakerKind_Mono        = 1,
  78.     kSSpSpeakerKind_Headphones    = 2
  79. };
  80.  
  81.  
  82. /*    This is the data type is used with the SndGet/SetInfo selector                */
  83. /*    siSSpSpeakerSetup = '3dst'                                                    */
  84.  
  85. struct SSpSpeakerSetupData {
  86.     UInt32                             speakerKind;                /* Speaker configuration                */
  87.     float                             speakerAngle;                /* Angle formed by user and speakers    */
  88.  
  89.     UInt32                             reserved0;                    /* Reserved for future use -- set to 0    */
  90.     UInt32                             reserved1;                    /* Reserved for future use -- set to 0    */
  91. };
  92. typedef struct SSpSpeakerSetupData        SSpSpeakerSetupData;
  93.  
  94. enum {
  95.     kSSpMedium_Air                = 0,
  96.     kSSpMedium_Water            = 1
  97. };
  98.  
  99.  
  100.  
  101. enum {
  102.     kSSpSourceMode_Unfiltered    = 0,                            /* No filtering applied                    */
  103.     kSSpSourceMode_Localized    = 1,                            /* Localized by source position            */
  104.     kSSpSourceMode_Ambient        = 2,                            /* Coming from all around                */
  105.     kSSpSourceMode_Binaural        = 3                                /* Already binaurally localized            */
  106. };
  107.  
  108.  
  109.  
  110. struct SSpLocationData {
  111.     float                             elevation;                    /* Angle of the meridian -- pos is up    */
  112.     float                             azimuth;                    /* Angle of the parallel -- pos is left    */
  113.     float                             distance;                    /* Distance between source and listener    */
  114.     float                             projectionAngle;            /* Cos(angle) between cone and listener    */
  115.     float                             sourceVelocity;                /* Speed of source toward the listener    */
  116.     float                             listenerVelocity;            /*Speed of listener toward the source    */
  117. };
  118. typedef struct SSpLocationData            SSpLocationData;
  119.  
  120. struct SSpVirtualSourceData {
  121.     float                             attenuation;                /* Attenuation factor                    */
  122.     SSpLocationData                 location;                    /* Location of virtual source            */
  123. };
  124. typedef struct SSpVirtualSourceData        SSpVirtualSourceData;
  125. /*    This is the data type is used with the SndGet/SetInfo selector                */
  126. /*    siSSpLocalization = '3dif'                                                    */
  127.  
  128. struct SSpLocalizationData {
  129.     UInt32                             cpuLoad;                    /* CPU load vs. quality -- 0 is best    */
  130.  
  131.     UInt32                             medium;                        /* Medium for sound propagation            */
  132.     float                             humidity;                    /* Humidity when medium is air            */
  133.     float                             roomSize;                    /* Reverb model -- distance bet. walls    */
  134.     float                             roomReflectivity;            /*Reverb model -- bounce attenuation    */
  135.     float                             reverbAttenuation;            /*Reverb model -- mix level            */
  136.  
  137.     UInt32                             sourceMode;                    /* Type of filtering to apply            */
  138.     float                             referenceDistance;            /*Nominal distance for recording        */
  139.     float                             coneAngleCos;                /* Cos(angle/2) of attenuation cone        */
  140.     float                             coneAttenuation;            /* Attenuation outside the cone            */
  141.     SSpLocationData                 currentLocation;            /* Location of the sound                 */
  142.  
  143.     UInt32                             reserved0;                    /* Reserved for future use -- set to 0    */
  144.     UInt32                             reserved1;                    /* Reserved for future use -- set to 0    */
  145.     UInt32                             reserved2;                    /* Reserved for future use -- set to 0    */
  146.     UInt32                             reserved3;                    /* Reserved for future use -- set to 0    */
  147.  
  148.     UInt32                             virtualSourceCount;            /*Number of reflections                */
  149.     SSpVirtualSourceData             virtualSource[4];            /*The reflections                        */
  150. };
  151. typedef struct SSpLocalizationData        SSpLocalizationData;
  152. #if TARGET_CPU_PPC
  153. typedef CALLBACK_API_C( Boolean , SSpEventProcPtr )(EventRecord *inEvent);
  154. /*******************************************************************************
  155.  *    Global functions
  156.  ******************************************************************************/
  157. EXTERN_API_C( OSStatus )
  158. SSpConfigureSpeakerSetup        (SSpEventProcPtr         inEventProcPtr);
  159.  
  160. EXTERN_API_C( OSStatus )
  161. SSpGetCPULoadLimit                (UInt32 *                outCPULoadLimit);
  162.  
  163.  
  164. /*******************************************************************************
  165.  *    Routines for Maniulating Listeners
  166.  ******************************************************************************/
  167. typedef struct OpaqueSSpListenerReference*  SSpListenerReference;
  168. EXTERN_API_C( OSStatus )
  169. SSpListener_New                    (SSpListenerReference *    outListenerReference);
  170.  
  171. EXTERN_API_C( OSStatus )
  172. SSpListener_Dispose                (SSpListenerReference     inListenerReference);
  173.  
  174. EXTERN_API_C( OSStatus )
  175. SSpListener_SetTransform        (SSpListenerReference     inListenerReference,
  176.                                  const TQ3Matrix4x4 *    inTransform);
  177.  
  178. EXTERN_API_C( OSStatus )
  179. SSpListener_GetTransform        (SSpListenerReference     inListenerReference,
  180.                                  TQ3Matrix4x4 *            outTransform);
  181.  
  182. EXTERN_API_C( OSStatus )
  183. SSpListener_SetPosition            (SSpListenerReference     inListenerReference,
  184.                                  const TQ3Point3D *        inPosition);
  185.  
  186. EXTERN_API_C( OSStatus )
  187. SSpListener_GetPosition            (SSpListenerReference     inListenerReference,
  188.                                  TQ3Point3D *            outPosition);
  189.  
  190. EXTERN_API_C( OSStatus )
  191. SSpListener_SetOrientation        (SSpListenerReference     inListenerReference,
  192.                                  const TQ3Vector3D *    inOrientation);
  193.  
  194. EXTERN_API_C( OSStatus )
  195. SSpListener_GetOrientation        (SSpListenerReference     inListenerReference,
  196.                                  TQ3Vector3D *            outOrientation);
  197.  
  198. EXTERN_API_C( OSStatus )
  199. SSpListener_SetUpVector            (SSpListenerReference     inListenerReference,
  200.                                  const TQ3Vector3D *    inUpVector);
  201.  
  202. EXTERN_API_C( OSStatus )
  203. SSpListener_GetUpVector            (SSpListenerReference     inListenerReference,
  204.                                  TQ3Vector3D *            outUpVector);
  205.  
  206. EXTERN_API_C( OSStatus )
  207. SSpListener_SetCameraPlacement    (SSpListenerReference     inListenerReference,
  208.                                  const TQ3CameraPlacement * inCameraPlacement);
  209.  
  210. EXTERN_API_C( OSStatus )
  211. SSpListener_GetCameraPlacement    (SSpListenerReference     inListenerReference,
  212.                                  TQ3CameraPlacement *    outCameraPlacement);
  213.  
  214. EXTERN_API_C( OSStatus )
  215. SSpListener_SetVelocity            (SSpListenerReference     inListenerReference,
  216.                                  const TQ3Vector3D *    inVelocity);
  217.  
  218. EXTERN_API_C( OSStatus )
  219. SSpListener_GetVelocity            (SSpListenerReference     inListenerReference,
  220.                                  TQ3Vector3D *            outVelocity);
  221.  
  222. EXTERN_API_C( OSStatus )
  223. SSpListener_GetActualVelocity    (SSpListenerReference     inListenerReference,
  224.                                  TQ3Vector3D *            outVelocity);
  225.  
  226. EXTERN_API_C( OSStatus )
  227. SSpListener_SetMedium            (SSpListenerReference     inListenerReference,
  228.                                  UInt32                 inMedium,
  229.                                  float                     inHumidity);
  230.  
  231. EXTERN_API_C( OSStatus )
  232. SSpListener_GetMedium            (SSpListenerReference     inListenerReference,
  233.                                  UInt32 *                outMedium,
  234.                                  float *                outHumidity);
  235.  
  236. EXTERN_API_C( OSStatus )
  237. SSpListener_SetReverb            (SSpListenerReference     inListenerReference,
  238.                                  float                     inRoomSize,
  239.                                  float                     inRoomReflectivity,
  240.                                  float                     inReverbAttenuation);
  241.  
  242. EXTERN_API_C( OSStatus )
  243. SSpListener_GetReverb            (SSpListenerReference     inListenerReference,
  244.                                  float *                outRoomSize,
  245.                                  float *                outRoomReflectivity,
  246.                                  float *                outReverbAttenuation);
  247.  
  248. EXTERN_API_C( OSStatus )
  249. SSpListener_SetMetersPerUnit    (SSpListenerReference     inListenerReference,
  250.                                  float                     inMetersPerUnit);
  251.  
  252. EXTERN_API_C( OSStatus )
  253. SSpListener_GetMetersPerUnit    (SSpListenerReference     inListenerReference,
  254.                                  float *                outMetersPerUnit);
  255.  
  256.  
  257. /*******************************************************************************
  258.  *    Routines for Manipulating Sources
  259.  ******************************************************************************/
  260. typedef struct OpaqueSSpSourceReference*  SSpSourceReference;
  261. EXTERN_API_C( OSStatus )
  262. SSpSource_New                    (SSpSourceReference *    outSourceReference);
  263.  
  264. EXTERN_API_C( OSStatus )
  265. SSpSource_Dispose                (SSpSourceReference     inSourceReference);
  266.  
  267. EXTERN_API_C( OSStatus )
  268. SSpSource_CalcLocalization        (SSpSourceReference     inSourceReference,
  269.                                  SSpListenerReference     inListenerReference,
  270.                                  SSpLocalizationData *    out3DInfo);
  271.  
  272. EXTERN_API_C( OSStatus )
  273. SSpSource_SetTransform            (SSpSourceReference     inSourceReference,
  274.                                  const TQ3Matrix4x4 *    inTransform);
  275.  
  276. EXTERN_API_C( OSStatus )
  277. SSpSource_GetTransform            (SSpSourceReference     inSourceReference,
  278.                                  TQ3Matrix4x4 *            outTransform);
  279.  
  280. EXTERN_API_C( OSStatus )
  281. SSpSource_SetPosition            (SSpSourceReference     inSourceReference,
  282.                                  const TQ3Point3D *        inPosition);
  283.  
  284. EXTERN_API_C( OSStatus )
  285. SSpSource_GetPosition            (SSpSourceReference     inSourceReference,
  286.                                  TQ3Point3D *            outPosition);
  287.  
  288. EXTERN_API_C( OSStatus )
  289. SSpSource_SetOrientation        (SSpSourceReference     inSourceReference,
  290.                                  const TQ3Vector3D *    inOrientation);
  291.  
  292. EXTERN_API_C( OSStatus )
  293. SSpSource_GetOrientation        (SSpSourceReference     inSourceReference,
  294.                                  TQ3Vector3D *            outOrientation);
  295.  
  296. EXTERN_API_C( OSStatus )
  297. SSpSource_SetUpVector            (SSpSourceReference     inSourceReference,
  298.                                  const TQ3Vector3D *    inUpVector);
  299.  
  300. EXTERN_API_C( OSStatus )
  301. SSpSource_GetUpVector            (SSpSourceReference     inSourceReference,
  302.                                  TQ3Vector3D *            outUpVector);
  303.  
  304. EXTERN_API_C( OSStatus )
  305. SSpSource_SetCameraPlacement    (SSpSourceReference     inSourceReference,
  306.                                  const TQ3CameraPlacement * inCameraPlacement);
  307.  
  308. EXTERN_API_C( OSStatus )
  309. SSpSource_GetCameraPlacement    (SSpSourceReference     inSourceReference,
  310.                                  TQ3CameraPlacement *    outCameraPlacement);
  311.  
  312. EXTERN_API_C( OSStatus )
  313. SSpSource_SetVelocity            (SSpSourceReference     inSourceReference,
  314.                                  const TQ3Vector3D *    inVelocity);
  315.  
  316. EXTERN_API_C( OSStatus )
  317. SSpSource_GetVelocity            (SSpSourceReference     inSourceReference,
  318.                                  TQ3Vector3D *            outVelocity);
  319.  
  320. EXTERN_API_C( OSStatus )
  321. SSpSource_GetActualVelocity        (SSpSourceReference     inSourceReference,
  322.                                  TQ3Vector3D *            outVelocity);
  323.  
  324. EXTERN_API_C( OSStatus )
  325. SSpSource_SetCPULoad            (SSpSourceReference     inSourceReference,
  326.                                  UInt32                 inCPULoad);
  327.  
  328. EXTERN_API_C( OSStatus )
  329. SSpSource_GetCPULoad            (SSpSourceReference     inSourceReference,
  330.                                  UInt32 *                outCPULoad);
  331.  
  332. EXTERN_API_C( OSStatus )
  333. SSpSource_SetMode                (SSpSourceReference     inSourceReference,
  334.                                  UInt32                 inMode);
  335.  
  336. EXTERN_API_C( OSStatus )
  337. SSpSource_GetMode                (SSpSourceReference     inSourceReference,
  338.                                  UInt32 *                outMode);
  339.  
  340. EXTERN_API_C( OSStatus )
  341. SSpSource_SetReferenceDistance    (SSpSourceReference     inSourceReference,
  342.                                  float                     inReferenceDistance);
  343.  
  344. EXTERN_API_C( OSStatus )
  345. SSpSource_GetReferenceDistance    (SSpSourceReference     inSourceReference,
  346.                                  float *                outReferenceDistance);
  347.  
  348. EXTERN_API_C( OSStatus )
  349. SSpSource_SetSize                (SSpSourceReference     inSourceReference,
  350.                                  float                     inLength,
  351.                                  float                     inWidth,
  352.                                  float                     inHeight);
  353.  
  354. EXTERN_API_C( OSStatus )
  355. SSpSource_GetSize                (SSpSourceReference     inSourceReference,
  356.                                  float *                outLength,
  357.                                  float *                outWidth,
  358.                                  float *                outHeight);
  359.  
  360. EXTERN_API_C( OSStatus )
  361. SSpSource_SetAngularAttenuation    (SSpSourceReference     inSourceReference,
  362.                                  float                     inConeAngle,
  363.                                  float                     inConeAttenuation);
  364.  
  365. EXTERN_API_C( OSStatus )
  366. SSpSource_GetAngularAttenuation    (SSpSourceReference     inSourceReference,
  367.                                  float *                outConeAngle,
  368.                                  float *                outConeAttenuation);
  369.  
  370. #endif  /* TARGET_CPU_PPC */
  371.  
  372.  
  373. /*******************************************************************************
  374.  *    LATE-BREAKING NEWS
  375.  *
  376.  *    After the documentation was completed, it was decided that the SSpSetup
  377.  *    were not specific enough.  We renamed them to SSpSpeakerSetup.  These
  378.  *    #defines allow code to be written per the documentation.  But please use
  379.  *    the new, longer names, as the #defines will be removed in a later release.
  380.  ******************************************************************************/
  381. #define SSpConfigureSetup        SSpConfigureSpeakerSetup
  382.  
  383. #define siSSpSetup                siSSpSpeakerSetup
  384. #define SSpSetupData            SSpSpeakerSetupData
  385.  
  386.  
  387. /*******************************************************************************
  388.  *    MORE LATE-BREAKING NEWS
  389.  *
  390.  *    The SndGetInfo selector siSSpFilterVersion and datatype SSpFilterVersionData
  391.  *    have been removed in favor of an alternate way of accessing filter version
  392.  *    information.  The following function may be used for this purpose.
  393.  *******************************************************************************
  394. // **************************** GetSSpFilterVersion ****************************
  395. // Finds the manufacturer and version number of the SoundSprocket filter that
  396. // may be installed.  inManufacturer should be the manufacturer code specified
  397. // at the installation time, which may be zero to allow any manufacturer.
  398. // If no error is encountered, outManufacturer is set to the actual manufacturer
  399. // code and outMajorVersion and outMinorVersion are set to the component
  400. // specification level and manufacturer's implementation revision, respectively.
  401. OSStatus GetSSpFilterVersion(
  402.     OSType                    inManufacturer,
  403.     OSType*                    outManufacturer,
  404.     UInt32*                    outMajorVersion,
  405.     UInt32*                    outMinorVersion)
  406. {
  407.     OSStatus                err;
  408.     ComponentDescription    description;
  409.     Component                componentRef;
  410.     UInt32                    vers;
  411.     
  412.     // Set up the component description
  413.     description.componentType            = kSoundEffectsType;
  414.     description.componentSubType        = kSSpLocalizationSubType;
  415.     description.componentManufacturer    = inManufacturer;
  416.     description.componentFlags            = 0;        
  417.     description.componentFlagsMask        = 0;    
  418.     
  419.     // Find a component matching the description
  420.     componentRef = FindNextComponent(nil, &description);
  421.     if (componentRef == nil)  return couldntGetRequiredComponent;
  422.     
  423.     // Get the component description (for the manufacturer code)
  424.     err = GetComponentInfo(componentRef, &description, nil, nil, nil);
  425.     if (err != noErr)  return err;
  426.     
  427.     // Get the version composite
  428.     vers = (UInt32) GetComponentVersion((ComponentInstance) componentRef);
  429.     
  430.     // Return the results
  431.     *outManufacturer = description.componentManufacturer;
  432.     *outMajorVersion = HiWord(vers);
  433.     *outMinorVersion = LoWord(vers);
  434.     
  435.     return noErr;
  436. }
  437. *******************************************************************************/
  438.  
  439.  
  440.  
  441. #if PRAGMA_STRUCT_ALIGN
  442.     #pragma options align=reset
  443. #elif PRAGMA_STRUCT_PACKPUSH
  444.     #pragma pack(pop)
  445. #elif PRAGMA_STRUCT_PACK
  446.     #pragma pack()
  447. #endif
  448.  
  449. #ifdef PRAGMA_IMPORT_OFF
  450. #pragma import off
  451. #elif PRAGMA_IMPORT
  452. #pragma import reset
  453. #endif
  454.  
  455. #ifdef __cplusplus
  456. }
  457. #endif
  458.  
  459. #endif /* __SOUNDSPROCKET__ */
  460.  
  461.